[Issues 471, 472, 480] Guideline 6 API requirements

Hello,

Per my action item from the 16 May teleconference [1], please
consider this proposal for changes to some of the checkpoints in
Guideline 6. This proposal intends to address issues 471 [2], 472
[3], and 480 [4].

Tim, Rich, Scott: Please indicate your support for this proposal.

[1] http://lists.w3.org/Archives/Public/w3c-wai-ua/2001AprJun/0161
[2] http://server.rehab.uiuc.edu/ua-issues/issues-linear-lc3.html#471
[3] http://server.rehab.uiuc.edu/ua-issues/issues-linear-lc3.html#472
[4] http://server.rehab.uiuc.edu/ua-issues/issues-linear-lc3.html#480

Reference document: 11 April 2001 draft:
 http://www.w3.org/WAI/UA/WD-UAAG10-20010411/

------------
Introduction
------------

The proposal attempts to provide answers to the following
questions in a clear and consistent manner:

 a) What is a "standard" API?
 b) Which is more important: implementing some API, or
    implementing a standard API?
 c) What happens when there is no standard API?
 d) What happens when the API doesn't meet the developer's needs?
 e) What happens when the developer has an API that is "better"
    than the standard API? Should conformance be possible when
    the user agent implements a better API?

I list all of these questions because they have all been asked at
one time or another. They also may make good FAQ questions.

At the 16 May teleconference, the Working Group renewed their
commitment to requiring standard APIs as a way of ensuring
interoperability. However, the WG moved in the direction of
acknowledging the following hierarchy of API preferences:

 1) Prefer an API that has been standardized (e.g., by W3C).
    The WG distinguished a standard API that is "broken" from 
    one that is non-standard. The WG has said that it's fine to
    work around the former, but that if there is an API and
    it's not broken, it's preferred over a non-standard API.
 
 2) Otherwise, prefer an API that enables interoperability by
    having at least the following characteristics:

     a) It is publicly documented
     b) More than one assistive technology may use it
        for interaction with a conforming user agent.
 
 3) Otherwise, there is a risk that the API will not 
    meet our expectations of ensuring that assistive technology
    developers will have available and robuts APIs, or that
    the cost of developing to N different APIs will be prohibitive.
    (For more arguments, refer to email from Rich [5] and Tim [6]).

    Note: The WG recognizes that user agents and assistive
    technologies may already be deployed having implemented APIs
    that do not satisfy the interoperability requirements of this
    document. Specific user agent/AT combinations may provide
    accessible solutions for some users today (and that's good),
    but if the user agent doesn't satisfy the requirements of
    Guideline 6, it does not meet the WG's expectations about
    interoperability and the desirability of having a choice of
    assistive technologies.

[5] http://lists.w3.org/Archives/Public/w3c-wai-ua/2001AprJun/0132
[6] http://lists.w3.org/Archives/Public/w3c-wai-ua/2001AprJun/0156

------------------------
1) Definition of "standard API"
------------------------

A "standard API" is a publicly documented API that is the result
of a standards process (e.g., the W3C Recommendation track). For
the purposes of this document "de facto standards" and
proprietary operating environment APIs do not qualify as standard
APIs.

<DELETE from definition of API>
As part of encouraging interoperability, this document recommends
using standard APIs where possible, although this document does
not define in all cases how those APIs are standardized (i.e.,
whether they are defined by specifications such as W3C
Recommendations, defined by an operating environment vendor, de
facto standards, etc.).
</DELETE from definition of API>

Comment: The above definition may sound like a dramatic change,
but as the checkpoint below reveal, it is only one of definition.

----------------------------
2) Changes to G6 checkpoints
----------------------------

Summary: Guideline 6 checkpoints can be organized as follows
(and this might be useful in the Guideline prose):

 a) What information must be made available through an API.
 b) Which APIs must be used to provide this information.
 c) Constraints on providing this information.

More specifically:

 a) What information must be made available through an API:
    
    - HTML and XML content (6.1, 6.2)
    - Non-HTML/XML markup content (6.3)
    - CSS content when CSS implemented (6.9)
    - User interface controls (6.4)
    - Changes to content and user interface controls (6.5)

    Note: Write access is always limited to what the user can do
          through the UI anyway.

 b) Which APIs must be used to provide this information:

    b1) For HTML, XML, and CSS, use the DOM (6.1, 6.2, and 6.9)
    b2) Otherwise, use

      - Standard APIs or APIs designed to benefit accessibility (6.6)
      - Standard input and output APIs (6.6), and specifically
        the standard keyboard APIs (6.7)
    
 c) Constraints on providing information through an API:

    - Support character encodings (6.8)
    - Exchange information in a timely manner (6.10)

Please consider the following reorganization based on this model
and our discussions. There are no changes proposed for
checkpoints 6.1, 6.2, 6.8, 6.9, and 6.10.

<NEW 6.3>
  For markup languages other than HTML and XML, provide
  programmatic read access to content.  Provide programmatic
  write access for those parts of content that the user can
  modify through the user interface. Content only.
</NEW 6.3>

<NEW 6.4>
 Provide programmatic read access to user agent user interface
 controls.  Provide programmatic write access to those controls
 of the user agent user interface that the user can modify
 through the user interface.  For security reasons, user agents
 are not required to allow instructions in content to modify user
 agent user interface controls. User agent only.

  Note: This checkpoint is designed to enable users to interact
  with the user agent user interface controls through assistive
  technologies.
</NEW 6.4>

<NEW 6.5>
 Provide programmatic alert of changes to content, user interface
 controls, selection, content focus, and user interface focus.
 Both content and user agent.
</NEW 6.5>

<DELETE 6.6>
 Refer to new 6.X below.
</DELETE 6.6>

<NEW 6.X>
 To satisfy the requirements of each checkpoint 6.3, 6.4, and
 6.5, implement at least one API that is either (a) a standard
 API or (b) one designed to enable interoperability with
 assistive technologies. If neither type of API is available, or
 if available APIs do not enable the user agent to satisfy the
 requirements of the checkpoint, implement at least one publicly
 documented API to satisfy the requirements of the checkpoint
 <em>and</em> follow operating environment conventions for
 the use of input and output APIs.

    Note: User agents should follow operating environment
    conventions for the use of input and output APIs in all 
    cases.
</NEW 6.X>

Comment: This proposal differs slightly from our discussion at
the teleconference.

 - The old checkpoint 6.6 has been folded into this one. It
 considers standard APIs on par with ones designed to promote
 interoperability with assistive technologies.  Thus, to satisfy
 checkpoint 6.5, a user agent could provide alert of changes
 through either the DOM Events API or MSAA.

 - The checkpoint does not talk about how APIs satisfy "the
 requirements of the document" because the API requirements we
 are talking about are all in checkpoints 6.3, 6.4, and 6.5. The
 other requirements outside of Guideline 6 are meant to be
 satisfied through the UI, through config files, on the Web
 (documentation), etc. but NOT through APIs. This, in my opinion,
 tightens up the document significantly.

 - The second part of the checkpoint does not talk about
 the publicly documented APIs having to enable interoperability 
 since that's now covered by the first part of the checkpoint.

<NEW 6.7>
 Follow operating environment conventions when implementing
 APIs for the keyboard. 

    Note: Operating environment conventions may require more than
    one API for the keyboard. For instance, for Japanese and
    Chinese, input may be processed in two stages, with an API
    for each.  
</NEW 6.7>

----------------------------
3) Changes to conformance
----------------------------

To section 3.6 "Well-formed conformance claims", add two
requirements:

 - The claim must indicate which APIs are used to satisfy the
 checkpoints of Guideline 6.

 - The claim must indicate which formats are used to satisfy the
 checkpoints (both for content labels and Guideline 8). Note:
 This second requirement was not discussed at the teleconference,
 but I recall it here since it is part of another proposal.
  
----------------------------
4) Techniques
----------------------------

I think that in the Techniques Document we *must* be able to
provide an example of an API that would satisfy checkpoints 6.3,
6.4, and 6.5. For example:

 6.3: ?? Help!
 6.4: On Windows, MSAA. For Java, Java Access API.
 6.5: On Windows, MSAA. Or the DOM Events model.
 6.X: Any DOM API, MSAA, Java Access API, others?

Please make additional suggestions!

-- 
Ian Jacobs (ij@w3.org)   http://www.w3.org/People/Jacobs
Tel:                     +1 831 457-2842
Cell:                    +1 917 450-8783

Received on Thursday, 17 May 2001 20:56:02 UTC